Replication Package: Repression Works (just not in moderation)
---------------------------------------------------------------------

Updated 11/30/2022.

# Table of Contents
1. [Overview](#overview)
2. [Data Sources](#data)
3. [System Requirements](#system)
4. [Instructions](#instructions)


# Overview <a name="overview"></a>

The code in this replication package reconstructs the empirical analyses in Zhukov, "Repression Works (just not in moderation)," forthcoming in *Comparative Political Studies*. One R script will run all of the code to generate the figures and tables in the main body of the paper and all empirical results in the Online Appendix (`master.R`). The replicator should expect the code to run for about 6-12 hours, depending on system configuration.

## Contents of Replication Package

- `README.md`: this file
- `master.R`: R script that executes all replication code in sequence
- `Code/`: directory with R scripts sourced by `master.R`
    - `run1_setup.R`: R script to install missing packages and dependencies
    - `run2_main.R`: R script to replicate all figures and tables in main text
    - `functions.R`: R script with custom functions sourced by `run2_main.R` 
- `Data/`: directory with data files used by `run2_main.R` 
    - `Borders/`: country and administrative boundary geometries
        - `GADM_36_ADM0_wgs.tar.xz `: tarball with high-resolution country boundary geometries
        - `GADM_[COUNTRY ISO3]_[YEAR]_[LEVEL]_wgs.geojson`: simplified sub-national administrative boundary geometries
        - `PRIOGRID_RUS_2000_PRIO_wgs.geojson`: grid cell boundary geometries for Russia
        - `wrld_simpl.geojson`: low-resolution country boundary geometries
    - `Covariates/`: data files on sub-national covariates 
        - `ETOPO1_RUS_GADM2015_ADM2.RDS`: elevation data for level-2 Russian administrative units
        - `ETOPO1_RUS_PRIOGRID2000_PRIO.RDS`: elevation data for PRIO grid cells in Russia
        - `GHS_RUS_GADM2015_ADM2.RDS`: population data for level-2 Russian administrative units
        - `NOAAv501_RUS_GADM2015_ADM2.RDS`: weather data for level-2 Russian administrative units
        - `NOAAv501_RUS_PRIOGRID2000_PRIO.RDS`: weather data for PRIO grid cells in Russia
    - `CrossNational/:` data files on cross-national covariates
        -  `cy_data.RDS`: main country-year level data file
    - `EventData/`: xSub political violence data files
        - `xSub_[DATA SOURCE]_[COUNTRY ISO3]_[BOUNDARY SET]_[SPATIAL UNIT]_[TIME UNIT].RDS`: political violence event data (spatial panel)
        - `xSub_yzCaucasus2000_RUS_event.RDS`: political violence event data (individual events) 
- `Output/`: directory with files generated by `run2_main.R`
    - `Intermediate_Objects/`: directory with model and simulation results
    - `fig*.png`: figures in PNG format 
    - `tab*.tex`: tables in LaTeX format 


# Data Sources <a name="data"></a>

## 1. Borders

Data on country and administrative boundaries are from the Database of Global Administrative Areas. The files provided with the replication package have simplified geometries (to reduce processing time). The original data can be downloaded from https://gadm.org. We used versions 2.8 (2015) and 3.6 (2018). For licensing terms, see https://gadm.org/license.html.

Citation info:
- GADM. *Database of Global Administrative Areas*, Version 3.6 (2018).

Data objects provided as part of this archive:
- `Data/Borders/GADM_*`

Data on rectangular grid cell boundaries for India are from PRIO-GRID 2.0. The files provided with the replication package have been subsetted to include only those overlapping with India in its 2022 boundaries. The original data can be downloaded from https://grid.prio.org. We used version 2.0. For licensing terms, see https://grid.prio.org/#/codebook.

Citation info:
- Tollefsen, Andreas Forø, Håvard Strand and Halvard Buhaug. "PRIO-GRID: A unified spatial data structure." *Journal of Peace Research* 49, no. 2 (2012): 363-374. doi: 10.1177/0022343311431287

Data objects provided as part of this archive:
- `Data/Borders/PRIOGRID_RUS_2000_PRIO_wgs.geojson`


## 2. Covariates

Data on elevation are from the  ETOPO1 Global Relief Model (Bedrock) project. The files provided with the replication package have been pre-processed as aggregates for discrete spatial units. The original files can be downloaded from  https://ngdc.noaa.gov/mgg/global/global.html. We used the 2009 version. These data are in the public domain.

Citation info:
- NOAA National Geophysical Data Center. *2009: ETOPO1 1 Arc-Minute Global Relief Model*. NOAA National Centers for Environmental Information.  

Data objects provided as part of this archive:
- `ETOPO1_RUS_GADM2015_ADM2.RDS`
- `ETOPO1_RUS_PRIOGRID2000_PRIO.RDS`

Data on weather are from the NOAA Terrestrial Air Temperature and Precipitation project. The files provided with the replication package have been pre-processed as aggregates for discrete spatial units. The original files can be downloaded from https://data.noaa.gov/dataset/dataset/terrestrial-air-temperature-and-precipitation-1900-2014-gridded-monthly-time-series. We used version 5.01. These data are in the public domain.

Citation info:
- Matsuura, Kenji; Willmott, Cort, 2017, *Terrestrial Air Temperature and Precipitation: 1900-2014 Gridded Monthly Time Series (v5.01)*, National Oceanic and Atmospheric Administration

Data objects provided as part of this archive:
- `NOAAv501_RUS_GADM2015_ADM2.RDS`
- `NOAAv501_RUS_PRIOGRID2000_PRIO.RDS`

Data on population are from the Global Human Settlement Layer Multitemporal project. The files provided with the replication package have been pre-processed as aggregates for discrete spatial units. The original files can be downloaded from https://ghsl.jrc.ec.europa.eu/ghs_pop2019.php. We used version P2019. These data are in the public domain.

Citation info:
- Schiavina, Marcello, Sergio Freire and Kytt MacManus. *GHS population grid multitemporal* (1975, 1990, 2000, 2015) R2019A. European Commission, Joint Research Centre (2019).

Data objects provided as part of this archive:
- `GHS_RUS_GADM2015_ADM2.RDS`

## 3. Cross-National Data

Data on cross-national civil liberties and democracy measures are from the Varieties of Democracy project. The original files can be downloaded from https://www.v-dem.net/en/data/data-version-7-1/. We used version 7.1. These data are in the public domain.

Citation info:
- Coppedge, Michael, John Gerring, Staffan I. Lindberg, Svend-Erik Skaaning, Jan
Teorell, David Altman, Michael Bernhard, M. Steven Fish, Adam Glynn, Allen Hicken,
Carl Henrik Knutsen, Joshua Krusell, Anna Lührmann, Kyle L. Marquardt, Kelly
McMann, Valeriya Mechkova, Moa Olin, Pamela Paxton, Daniel Pemstein, Josefine
Pernes, Constanza Sanhueza Petrarca, Johannes von Römer, Laura Saxer, Brigitte
Seim, Rachel Sigman, Jeffrey Staton, Natalia Stepanova, and Steven Wilson. 2017. *V-
Dem [Country-Year/Country-Date] Dataset v7.1*, Varieties of Democracy (V-Dem)
Project.

Data objects provided as part of this archive:
- `Data/CrossNational/cy_data.RDS`

Data on peace years were constructed from the Correlates of War project. The original files can be downloaded from https://correlatesofwar.org/data-sets/cow-war/. We used version 4.0. These data are in the public domain.

Citation info:
- Sarkees, Meredith Reid and Frank Wayman (2010). *Resort to War: 1816-2007*. Washington DC: CQ Press.

Data objects provided as part of this archive:
- `Data/CrossNational/cy_data.RDS`

Data on human rights treaty ratification are from the from the United Nations Treaty Collection. The original files can be downloaded from https://treaties.un.org/Pages/Treaties.aspx?id=4&subid=A&clang=_en. These data are in the public domain.

Citation information: 
- United Nations Treaty Collection, 2019, *Multilateral Treaties Deposited with the Secretary-General*. CHAPTER IV: Human Rights.

Data objects provided as part of this archive:
- `Data/CrossNational/cy_data.RDS`



## 4. Sub-National Event Data

Data on political violence are from the Cross-National Data on Sub-National Violence (xSub) project. xSub integrates information on political violence from 23 open-source event data sources. The original files can be downloaded from http://cross-sub.org/. We used the 2021 version. These data are in the public domain.

Citation info:
- Zhukov, Yuri M., Christian Davenport, and Nadiya Kostyuk. "Introducing xSub: a new portal for cross-national data on sub-national violence." *Journal of Peace Research* 56, no. 4 (2019): 604-614.

Data objects provided as part of this archive:
- `Data/EventData/xSub_*`


# System Requirements <a name="system"></a>

## 1. Software Requirements

Portions of the code rely on forking to run in parallel on multicore systems, which requires Linux or Mac OS. Single-core processing is possible on Windows if `mc.cores = 1` in `parallel::mclapply`.

R version 3.6.3 (2020-02-29)
- Platform: `x86_64-pc-linux-gnu` (64-bit)
- Running under: Ubuntu 18.04.6 LTS
- The script `run1_setup.R` will install all missing packages and dependencies, and should be run prior to executing `run2_main.R`.
- Attached packages:
    - `boot` (1.3-25)
    - `CBPS` (0.21)
    - `countrycode` (1.1.2)
    - `data.table` (1.14.2)
    - `dplyr` (1.0.8)
    - `glmnnet` (3.0.2)
    - `lme4` (1.1-28)
    - `maptools` (0.9-9)
    - `MASS` (7.3-53)
    - `Matching` (4.9-7)
    - `Matrix` (1.2-18)
    - `mvtnorm` (1.1-0)
    - `numDeriv` (2016.8-1.1)
    - `parallel` (3.6.3)
    - `sf` (1.0-5)       
    - `sp` (1.5-0)
    - `survival` (3.3-1)
    - `xSub` (3.0.2)
    - `xtable` (1.8-4)


## 2. Hardware Requirements

Approximate time needed to reproduce the analyses on a standard (2022) desktop machine is 6-12 hours.

The code was last run on a 16-core (Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz) laptop with 64 GB of RAM, running Ubuntu 18.04.6 LTS. Computation took about 6 hours. 


# Instructions to Replicators <a name="instructions"></a>

1. Download the compressed file `Replication_CPS.tar.gz` from DataVerse. Extract the contents of the tarball to a directory of your choice. The extracted scripts and data files should be stored in the same prepared subdirectories as in the tarball. Do not move the files after unzipping. 
2. Edit the preamble to `master.R` to adjust the default working directory in `setwd()` to the unzipped folder's location on your system. The path should point to the directory that contains this file, `master.R`, and `functions.R`.
3. OPTION A (non-interactive): To execute everything in one go, open a new session in R and run `master.R`. This script with source all the code in the `Code/` directory.
4. OPTION B (interactive): To execute the code line by line, run the scripts in the following order (after setting the working directory in R):
    a. Run `Code/run1_setup.R` to set up the working environment. 
    b. Run `Code/run2_main.R` to replicate all figures and tables in the main text.
    
